package com.synthefact.daj.model;

/**
 * A channel is the communication mechanism between nodes.
 * <p>
 * Copyright (C) 2011  Synthefact
 *  <p>
 * Based on code from 
 * (c) 1997, Wolfgang Schreiner <Wolfgang.Schreiner@risc.uni-linz.ac.at>
 * http://www.risc.uni-linz.ac.at/software/daj
 */
public interface ChannelIf {

    /**
     * Get the sender on this channel.
     * 
     * @return the sender on this channel.
     */
    NodeIf getSender();

    /**
     * Sends a message on this channel.
     * 
     * @param msg
     *            the message to send.
     */
    void send(MessageIf msg);

    /**
     * Get the receiver on this channel.
     * 
     * @return the receiver on this channel.
     */
    NodeIf getReceiver();

    /**
     * Receive a {@link MessageIf} from the channel. This method blocks until
     * the message is received.
     * 
     * @return the message from the channel
     */
    MessageIf receive();

    /**
     * Receive a {@link MessageIf} from channel; do not block but poll at most
     * `n` times. If then no message is found, return null
     * 
     * @param n
     *            number of times to poll
     * @return the message from the channel, or {@code null} if no message is
     *         received.
     */
    MessageIf receive(int n);

    /**
     * Tests if there is a message available to receive on this channel.
     * 
     * @return true if there is a message available to receive on this channel.
     */
    boolean isReady();
}
